package javax.servlet;

import java.io.IOException;


/**
 * 定义一个可以接收客户端请求并可以将客户端请求转发给服务器上任何一种类型资源(例如 servlet,HTML文件或JSP文件)的对象.
 * Servlet容器创建的那个<code>RequestDispatcher</code>对象已经事先封装好了服务器端本地(或通过参数名提供给服务器的)资源.
 *
 *<p>设计这个接口时只打算用它来封装servlet,
 * 不过现在,Servlet容器也可以创建一个可以封装任何类型资源的
 * <code>RequestDispatcher</code>对象.
 *
 * @author 	Various
 * @version 	$Version$
 *
 * @see 	ServletContext#getRequestDispatcher(java.lang.String)
 * @see 	ServletContext#getNamedDispatcher(java.lang.String)
 * @see 	ServletRequest#getRequestDispatcher(java.lang.String)
 *
 */
 
public interface RequestDispatcher {





/**
 * 将Servlet中的一个请求转交给服务器上的另一个资源(例如 sevlet、JSP文件或HTML文件),
 * 方法允许Servlet在生成响应之前对请求和被转发到的那个资源进行预处理.
 * 
 *<p>可以通过<code>getRequestDispatcher()</code>获得<code>RequestDispatcher</code>的一个实例,
 * 但<code>ServletRequest</code> 对象应该拥有其自身的路径信息和一些已经与目标资源路径映射的参数.

 * <p><code>forward</code>方法应该在响应输出流刷新写入客户端前调用.
 * 如果响应流已经写入客户端,方法将会抛出<code>IllegalStateException</code>异常.
 * 响应缓冲区中未提交的响应输出流将会在 <code>forward<code> 方法执行之前自动清空.
 *
 * <p>request和response参数必须传递到调用者(servlet)的service方法,
 * 要么交由子类 {@link ServletRequestWrapper} 或 {@link ServletResponseWrapper}对他们进行封装.
 *
 *
 * @param request		由servlet生成的,描述客户端请求的{@link ServletRequest}对象
 *
 * @param response		servlet响应客户端请求的<code>ServletResponse</code>对象
 *      
 * @exception ServletException	目标资源抛出的异常
 *
 * @exception IOException		目标资源抛出的异常
 *
 * @exception IllegalStateException	如果响应流已经写入客户端
 *
 */

    public void forward(ServletRequest request, ServletResponse response)
	throws ServletException, IOException;




    /**
     * 将资源(例如 servlet、JSP页面或HTML文件)内容包含到响应流中.
     * 实质上方法默认启用了服务端按队列包含文件.
     *
     * <p>{@link ServletResponse}对象没有修改从调用者(servlet)那获得的路径信息和参数.
     * 包含了资源的servlet不能更改响应状态码或设置响应头;任何形式的尝试修改都将被视为无效.
     *
     *
     * * <p>request和response参数必须传递到调用者(servlet)的service方法,
     * 要么交由子类 {@link ServletRequestWrapper} 或 {@link ServletResponseWrapper}对他们进行封装.
     * <p>The request and response parameters must be either the same
     * objects as were passed to the calling servlet's service method or be
     * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
     * that wrap them.
     * 
     *
     *
     * @param request 			含有客户端请求的 {@link ServletRequest} 对象 
     *	
     *
     * @param response 			含有servlet响应流的 {@link ServletResponse} 对象 
     * 					
     *
     * @exception ServletException 	如果包含资源时产生异常
     *
     * @exception IOException 		如果包含资源时产生异常
     *
     *
     */
     
    public void include(ServletRequest request, ServletResponse response)
	throws ServletException, IOException;
}








